home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / doc / unix.doc < prev    next >
Text File  |  1993-07-05  |  10KB  |  522 lines
  1.  
  2.     UNIX.DOC (c)Copyright 1990, Matthew Dillon, All Rights Reserved
  3.  
  4. TABLE OF CONTENTS
  5.  
  6. c.lib/unix/access
  7. c.lib/unix/chdir
  8. c.lib/unix/dir
  9. c.lib/unix/fstat
  10. c.lib/unix/getcwd
  11. c.lib/unix/getenv
  12. c.lib/unix/sleep
  13. c.lib/unix/stat
  14. c.lib/unix/unlink
  15.  
  16.  
  17. unix/access                        unix/access
  18.  
  19.    NAME
  20.     access    - determine whether file is accessable
  21.  
  22.    SYNOPSIS
  23.     int r = access(filename, mode);
  24.     const char *filename;
  25.     int mode;
  26.  
  27.     UNIX call
  28.  
  29.    FUNCTION
  30.     Returns 0 on success, -1 if no access with the requested modes
  31.     may be gained.    filename is a pointer to a string that is
  32.     the filename we wish to check, modes is a set of modes we
  33.     expect the file to be able to do.
  34.  
  35.     the modes may be one or more of the following OR'd together.
  36.  
  37.     0   check for existance of file only
  38.     1   check execute permission for file
  39.     2   check write permission for file
  40.     4   check read permission for file
  41.  
  42.    EXAMPLE
  43.     /*
  44.      *  P.S. this is a dumb, slow, inefficient example
  45.      */
  46.  
  47.     #include <stdio.h>
  48.  
  49.     main(ac, av)
  50.     char *av[];
  51.     {
  52.         char *name;
  53.  
  54.         if (ac == 1) {
  55.         puts("Expected a file argument");
  56.         exit(1);
  57.         }
  58.         name = av[1];
  59.  
  60.         if (access(name, 0) == 0) {
  61.         puts("it exists");
  62.         if (access(name, 1) == 0)
  63.             puts("it is executable");
  64.         if (access(name, 2) == 0)
  65.             puts("I can write to it!");
  66.         if (access(name, 4) == 0)
  67.             puts("and even read from it!");
  68.         } else {
  69.         puts("Hmmm, that file does not exist");
  70.         }
  71.         return(0);
  72.     }
  73.  
  74.    INPUTS
  75.     char *filename;     file to check
  76.     int mode;        modes as specified above
  77.  
  78.    RESULTS
  79.     int r;            0 if modes available, -1 if not
  80.  
  81.    SEE ALSO
  82.     open, fopen
  83.  
  84.  
  85. unix/chdir                        unix/chdir
  86.  
  87.    NAME
  88.     chdir - change current directory
  89.  
  90.    SYNOPSIS
  91.     int r = chdir(path);
  92.     const char *path;
  93.  
  94.     UNIX call
  95.  
  96.    FUNCTION
  97.     Changes the current directory to the specified path returning 0 on
  98.     success and -1 on failure.
  99.  
  100.    NOTE
  101.     when a program exits, the original directory will be restored.
  102.  
  103.    EXAMPLE
  104.     #include <stdio.h>
  105.  
  106.     char buf[512];
  107.  
  108.     main(ac, av)
  109.     int ac;
  110.     char *av[];
  111.     {
  112.         getcwd(buf, sizeof(buf));
  113.         if (chdir("RAM:")) {
  114.         puts("Couldn't chdir into RAM:");
  115.         exit(1);
  116.         }
  117.         {
  118.         FILE *fp;
  119.         if (fp = fopen("yy", "w")) {
  120.             fclose(fp);
  121.             puts("created file yy in RAM:");
  122.         }
  123.         }
  124.         if (chdir(buf)) {
  125.         printf("Unable to chdir back into %s\n", buf);
  126.         }
  127.         return(0);
  128.     }
  129.  
  130.    INPUTS
  131.     char *path;    path to chdir into
  132.  
  133.    RESULTS
  134.     int r;        return value, 0 if ok, -1 if error
  135.  
  136.    SEE ALSO
  137.     getcwd
  138.  
  139.  
  140. unix/dir                        unix/dir
  141.  
  142.    NAME
  143.     dir - directory scanning routines
  144.  
  145.    SYNOPSIS
  146.     #include <sys/dir.h>
  147.  
  148.     DIR *dirhan = opendir(path);
  149.     struct direct *entry = readdir(dirhan);
  150.     (void) rewinddir(dirhan);
  151.     void closedir(dirhan);
  152.  
  153.     const char *path;
  154.     DIR *dirhan;
  155.  
  156.    FUNCTION
  157.     These are UNIX compatible directory scanning calls.  After openning
  158.     a directory with opendir(), you may scan it with successive
  159.     calls to readdir() until NULL is returned, then either
  160.     rewinddir() it for a rescan, or closedir() it when done.
  161.  
  162.     The DIR structure is private to the library.  Valid fields within
  163.     struct direct are d_name (the file name), and d_namlen (the length
  164.     of the file name, not usually needed).
  165.  
  166.     You can chdir() into the directory and stat() each entry to obtain
  167.     additional information.  Note that the UNIX directory scanning
  168.     routines will not be as efficient as the Amiga directory scanning
  169.     routines, but are portable.
  170.  
  171.    NOTE
  172.     Unlike the amiga directory scanning routines that use Lock()s,
  173.     these calls will automatically deallocate resources if the program
  174.     terminates.
  175.  
  176.     rewinddir()'s prototype returns an int .. this is for internal
  177.     use only, you should never use rewinddir()'s return value
  178.     yourself.
  179.  
  180.    EXAMPLE
  181.     #include <stdio.h>
  182.     #include <sys/dir.h>
  183.  
  184.     main(ac, av)
  185.     int ac;
  186.     char *av[];
  187.     {
  188.         DIR *dir;
  189.  
  190.         if (ac == 1) {
  191.         puts("test dir");
  192.         exit(1);
  193.         }
  194.         if (dir = opendir(av[1])) {
  195.         struct direct *entry;
  196.         while (entry = readdir(dir)) {
  197.             printf("%s\n", entry->d_name);
  198.         }
  199.         closedir(dir);
  200.         }
  201.         return(0);
  202.     }
  203.  
  204.    SEE ALSO
  205.     chdir
  206.  
  207.  
  208. unix/fstat                        unix/fstat
  209.  
  210.    NAME
  211.     fstat - stat a file descriptor
  212.  
  213.    SYNOPSIS
  214.     #include <sys/stat.h>
  215.  
  216.     int error = fstat(fd, &stat_buf);
  217.     struct stat stat_buf;
  218.  
  219.    FUNCTION
  220.     fstat() is a unix compatible call that returns information
  221.     pertaining to the file represented by an open file descriptor.
  222.  
  223.     see stat() for information on the struct stat fields.
  224.  
  225.    NOTE
  226.     fstat() works just like stat except you provide a UNIX file
  227.     descriptor (*NOT* an amigaDOS File Handle).  Under 2.0,
  228.     ExamineFH() will be used.  Under 1.3, the original path used to
  229.     open the file will be stat()'d, which ends up scanning the
  230.     directory if the file was open for exclusive access.
  231.  
  232.    INPUTS
  233.     int fd;         file descriptor to stat
  234.  
  235.     struct stat *sbuf;  address of stat structure that will be filled in
  236.  
  237.    RESULTS
  238.     int error;        0 on success, < 0 on error
  239.     none
  240.  
  241.    EXAMPLE
  242.     #include <stdio.h>
  243.     #include <fcntl.h>
  244.     #include <sys/stat.h>
  245.  
  246.     main(ac, av)
  247.     int ac;
  248.     char *av[];
  249.     {
  250.         int fd;
  251.         int r;
  252.         struct stat stat_buf;
  253.  
  254.         if (ac == 1) {
  255.         puts("test scratch_file");
  256.         exit(1);
  257.         }
  258.         fd = open(av[1], O_WRONLY | O_CREAT);
  259.         if (fd >= 0) {
  260.         r = fstat(fd, &stat_buf);
  261.         if (r < 0)
  262.             printf("Can't stat fd=%d\n", fd);
  263.         else
  264.             printf("File is %d bytes long\n", stat_buf.st_size);
  265.         close(fd);
  266.         }
  267.         return(0);
  268.     }
  269.  
  270.    SEE ALSO
  271.     chdir
  272.  
  273.  
  274. unix/getcwd                        unix/getcwd
  275.  
  276.    NAME
  277.     getcwd - get current working directory
  278.  
  279.    SYNOPSIS
  280.     char *path = getcwd(buf, max);
  281.  
  282.     non-standard call
  283.  
  284.    FUNCTION
  285.     Gets the current working directory and puts it into the specified
  286.     buffer buf.  If buf is NULL it will be malloc()d automatically.
  287.     buf is returned (or the malloced buffer if you passed NULL for buf).
  288.  
  289.     max specifies the maximum length of the path including the terminating
  290.     nul character.
  291.  
  292.     NULL is returned if any error occurs (such as malloc failing)
  293.  
  294.    EXAMPLE
  295.     #include <stdio.h>
  296.  
  297.     char buf[512];
  298.  
  299.     main(ac, av)
  300.     int ac;
  301.     char *av[];
  302.     {
  303.         getcwd(buf, sizeof(buf));
  304.         printf("Current directory is: %s\n", buf);
  305.         return(0);
  306.     }
  307.  
  308.    INPUTS
  309.     char *buf;    buffer to place current directory path into or
  310.             NULL if you want getcwd to allocate one
  311.  
  312.     int max;    maximum size of buffer
  313.  
  314.    RESULTS
  315.     char *path;    returns allocated buffer if you passed NULL for
  316.             buf, else returns the first argument.  Returns
  317.             NULL on error.
  318.  
  319.    SEE ALSO
  320.     chdir
  321.  
  322.  
  323. unix/getenv                        unix/getenv
  324.  
  325.    NAME
  326.     getenv - get enviroment variable
  327.  
  328.    SYNOPSIS
  329.     char *var = getenv(const char *name);
  330.  
  331.    FUNCTION
  332.     getenv() searches for and returns the ENV: enviroment variable
  333.     requested.  getenv() will cache variables so that requesting
  334.     the same variable repetitously does not allocate a new memory
  335.     buffer.
  336.  
  337.     getenv() allocates a buffer for each variable returned, so you
  338.     do not have to copy the return value from getenv().  This memory
  339.     is freed on program exit.  Do not attempt to free() a getenv()'d
  340.     variable!!
  341.  
  342.    EXAMPLE
  343.     #include <stdio.h>
  344.     #include <stdlib.h>
  345.  
  346.     main(ac, av)
  347.     int ac;
  348.     char *av[];
  349.     {
  350.         char *dccopts = getenv("DCCOPTS");
  351.         if (dccopts)
  352.         printf("DCCOPTS = %s\n", dccopts);
  353.         else
  354.         printf("You do not have a DCCOPTS enviroment variable!\n");
  355.         return(0);
  356.     }
  357.  
  358.    INPUTS
  359.     char *name;    Name of enviroment variable, on the amiga this
  360.             is not case sensitive.    On UNIX systems it is.
  361.  
  362.  
  363.    RESULTS
  364.     char *var;    contents of enviroment variable or NULL if the
  365.             variable could not be found.
  366.  
  367.    SEE ALSO
  368.  
  369.  
  370.  
  371. unix/sleep                        unix/sleep
  372.  
  373.    NAME
  374.     sleep - sleep for a period of time
  375.  
  376.    SYNOPSIS
  377.     sleep(n);
  378.     int n;
  379.  
  380.    FUNCTION
  381.     The sleep() function waits for a period of time specified in seconds.
  382.     sleep() can be interrupted by a ^C.
  383.  
  384.     NOTE: sleep's timekeeping is not very accurate.  On the Amiga,
  385.     sleep() is implemented with a loop of Delay(50); calls.
  386.  
  387.    EXAMPLE
  388.     #include <stdio.h>
  389.  
  390.     main(ac, av)
  391.     char *av[];
  392.     {
  393.         puts("Sleeping for 10 seconds");
  394.         sleep(10);
  395.         puts("That was a good rest");
  396.         return(0);
  397.     }
  398.  
  399.    INPUTS
  400.     int n;        number of seconds to sleep
  401.  
  402.    RESULTS
  403.     none
  404.  
  405.    SEE ALSO
  406.  
  407.  
  408. unix/stat                        unix/stat
  409.  
  410.    NAME
  411.     stat - stat a file by name
  412.  
  413.    SYNOPSIS
  414.     #include <sys/stat.h>
  415.  
  416.     int error = stat(name, &stat_buf);
  417.     const char *name;
  418.     struct stat stat_buf;
  419.  
  420.    FUNCTION
  421.     stat() is a unix compatible call that returns information
  422.     pertaining to the file represented by its name.
  423.  
  424.     If 0 is returned, the call succeeded and the fields will be
  425.     filled in as follows:
  426.  
  427.         st_mode        flags:  S_IFDIR    if directory
  428.                     S_IFREG    if regular file
  429.                     S_IREAD    if readable
  430.                     S_IWRITE    if writable
  431.                     S_IEXEC    if executable
  432.  
  433.         st_size        size of the file, in bytes
  434.  
  435.         st_blksize        512 (for now)
  436.  
  437.         st_blocks        a guess at the number of actual blocks the
  438.                 file takes up, including headers & side sectors
  439.  
  440.         st_ctime        time the file was last modified
  441.  
  442.         st_mtime        same as st_ctime
  443.  
  444.         st_dev        physical device ID (do not try to interpret this
  445.                 field, but it does represent the dos handler)
  446.  
  447.         st_ino        inode ID (usually a file block number on the
  448.                 amiga)
  449.  
  450.  
  451.    NOTE
  452.     On the amiga one normally cannot directly examine a file that
  453.     is exclusively locked.    If this case occurs, stat() will attempt
  454.     to scan the parent directory for the file and if *that* doesn't
  455.     work, returns -1.
  456.  
  457.  
  458.    INPUTS
  459.     char *name;        name of file to stat
  460.  
  461.     struct stat *sbuf;  address of stat structure that will be filled in
  462.  
  463.    RESULTS
  464.     int error;        0 on success, < 0 on error
  465.     none
  466.  
  467.    EXAMPLE
  468.     #include <stdio.h>
  469.     #include <fcntl.h>
  470.     #include <sys/stat.h>
  471.  
  472.     main(ac, av)
  473.     int ac;
  474.     char *av[];
  475.     {
  476.         int r;
  477.         struct stat stat_buf;
  478.  
  479.         if (ac == 1) {
  480.         puts("test scratch_file");
  481.         exit(1);
  482.         }
  483.         r = stat(av[1], &stat_buf);
  484.         if (r < 0)
  485.         printf("Can't stat %s\n", av[1]);
  486.         else
  487.         printf("File is %d bytes long\n", stat_buf.st_size);
  488.         return(0);
  489.     }
  490.  
  491.    SEE ALSO
  492.     chdir
  493.  
  494.  
  495. unix/unlink                        unix/unlink
  496.  
  497.    NAME
  498.     unlink - delete a file
  499.  
  500.    SYNOPSIS
  501.     int error = unlink(file);
  502.     char *file;
  503.  
  504.    FUNCTION
  505.     unlink() is *EXACTLY* remove().  unlink() exists for UNIX compatibility
  506.     only.
  507.  
  508.    NOTE
  509.     use rmdir() to delete a directory if you wish to maintain portability.
  510.  
  511.    EXAMPLE
  512.     Refer to the remove() manual page for an example
  513.  
  514.    INPUTS
  515.     char *file;        file name to delete
  516.  
  517.    RESULTS
  518.     int error;        0 on success, < 0 on failure
  519.  
  520.    SEE ALSO
  521.  
  522.